docs: resolve API drift in pkg/parser, pkg/workflow, pkg/cli, pkg/console#29925
Merged
Conversation
4 tasks
…ADMEs Closes #<issue>" Agent-Logs-Url: https://github.com/github/gh-aw/sessions/156e0434-ac97-42b1-b6bb-8cf9f967dfca Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Fix API drift in 4 packages as per specification audit
docs: resolve API drift in pkg/parser, pkg/workflow, pkg/cli, pkg/console
May 3, 2026
Closed
Contributor
There was a problem hiding this comment.
Pull request overview
Updates package READMEs to align published API/spec documentation with recently added exported types and helper functions across parser, workflow, cli, and console.
Changes:
- Documented workflow sandbox configuration, MCP scripts configuration/generators, and workflow header generation in
pkg/workflow/README.md. - Added inline sub-agent types and extraction/validation helpers to
pkg/parser/README.md. - Expanded exported types tables in
pkg/cli/README.mdand formalized the ProgressBar public API inpkg/console/README.md.
Show a summary per file
| File | Description |
|---|---|
| pkg/workflow/README.md | Adds spec entries for sandbox config, MCP scripts, and GenerateWorkflowHeader |
| pkg/parser/README.md | Documents inline sub-agent parsing types/functions |
| pkg/cli/README.md | Expands the exported-types spec table to cover newer CLI structs/types |
| pkg/console/README.md | Adds an explicit ProgressBar public API table |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comments suppressed due to low confidence (2)
pkg/workflow/README.md:198
SandboxConfigis described as supporting legacytype/configfields, butsandbox.configis now explicitly rejected as deprecated during validation (validateSandboxConfig returns a configuration error when SandboxConfig.Config != nil). The README should mention thatsandbox.configis deprecated/invalid and will fail compilation, so readers don’t copy an unsupported example.
| `SandboxType` | string alias | Sandbox type identifier (`"awf"`, `"default"`) |
| `SandboxConfig` | struct | Top-level sandbox configuration; supports new `agent`/`mcp` fields and legacy `type`/`config` fields |
| `AgentSandboxConfig` | struct | Agent-side sandbox configuration (ID, version, command, mounts, memory, env) |
| `SandboxRuntimeConfig` | struct | Anthropic Sandbox Runtime (SRT) configuration (filesystem, network, violations) |
pkg/workflow/README.md:390
- The
customInstructionsparameter is documented as being appended “verbatim”, but the implementation trims surrounding whitespace and trims each line before prefixing it as a comment. If callers rely on exact formatting (leading/trailing spaces, blank lines), they won’t get it—please update the wording to reflect the actual behavior.
| `GenerateWorkflowHeader` | `func(sourceFile, generatedBy, customInstructions string) string` | Generates the standard ASCII-art + regeneration-instructions header comment for compiled lock files; `sourceFile` is the `.md` source path, `generatedBy` names the generator, and `customInstructions` is appended verbatim |
- Files reviewed: 4/4 changed files
- Comments generated: 4
Comment on lines
+191
to
+200
| The sandbox subsystem controls which agent firewall (AWF) or sandbox runtime is used during workflow execution. | ||
|
|
||
| | Type | Kind | Description | | ||
| |------|------|-------------| | ||
| | `SandboxType` | string alias | Sandbox type identifier (`"awf"`, `"default"`) | | ||
| | `SandboxConfig` | struct | Top-level sandbox configuration; supports new `agent`/`mcp` fields and legacy `type`/`config` fields | | ||
| | `AgentSandboxConfig` | struct | Agent-side sandbox configuration (ID, version, command, mounts, memory, env) | | ||
| | `SandboxRuntimeConfig` | struct | Anthropic Sandbox Runtime (SRT) configuration (filesystem, network, violations) | | ||
| | `SRTNetworkConfig` | struct | Network configuration for SRT (allowed/blocked domains, Unix sockets) | | ||
| | `SRTFilesystemConfig` | struct | Filesystem configuration for SRT (denyRead, allowWrite, denyWrite) | |
|
|
||
| | Function | Signature | Description | | ||
| |----------|-----------|-------------| | ||
| | `GenerateWorkflowHeader` | `func(sourceFile, generatedBy, customInstructions string) string` | Generates the standard ASCII-art + regeneration-instructions header comment for compiled lock files; `sourceFile` is the `.md` source path, `generatedBy` names the generator, and `customInstructions` is appended verbatim | |
| |------------------|-----------|-------------| | ||
| | `NewProgressBar` | `func(total int64) *ProgressBar` | Creates a determinate progress bar for a known total byte count | | ||
| | `NewIndeterminateProgressBar` | `func() *ProgressBar` | Creates an indeterminate progress bar for operations of unknown size (WASM build only) | | ||
| | `(*ProgressBar).Update` | `func(current int64) string` | Updates progress and returns a formatted display string; in TTY mode renders a gradient bar, in non-TTY mode returns a text percentage | |
| | `InitOptions` | struct | Options for `InitRepository` | | ||
| | `JobData` | struct | Data for a single GitHub Actions job | | ||
| | `JobInfo` | struct | Metadata for a GitHub Actions job | | ||
| | `JobInfoWithDuration` | struct | `JobInfo` extended with a human-readable duration string | |
Contributor
|
Commit pushed:
|
This was referenced May 3, 2026
Copilot AI
added a commit
that referenced
this pull request
May 3, 2026
…sole (#29925) Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The spec-extractor workflow flagged 4 packages where source code outgrew their
README.mdspecifications (completeness scores:cli70%,parser80%,workflow75%,console95%).Changes
pkg/parser/README.mdInlineSubAgentstruct to the Types tablesub_agent_extractor.go:ExtractInlineSubAgents,ValidateInlineSubAgentsFrontmatter,ValidateInlineSubAgentsInBody,GetEngineSubAgentDir,GetEngineSubAgentExtpkg/workflow/README.mdThree new subsections:
SandboxConfig,AgentSandboxConfig,SandboxRuntimeConfig,SRTNetworkConfig,SRTFilesystemConfig,SandboxType+SandboxTypeAWF/SandboxTypeDefaultconstantsMCPScriptsConfig,MCPScriptToolConfig,MCPScriptParam,MCPScriptsToolJSON,MCPScriptsConfigJSON+MCPScriptsModeHTTP/MCPScriptsDirectoryconstants + 8 generator functions (GenerateMCPScriptsToolsConfig,GenerateMCPScriptsMCPServerScript,GenerateMCPScriptJavaScriptToolScript, etc.)GenerateWorkflowHeader(sourceFile, generatedBy, customInstructions string) stringpkg/cli/README.md~45 types added to the "Additional Exported Types" table, covering recently-added structs that had no spec entries:
AuditComparisonClassification,AuditComparisonIntDelta,AuditComparisonMCPFailureDelta,AuditComparisonRecommendation,AuditComparisonStringDeltaBashCommandsDiff,FirewallDiff,FirewallDiffSummary,RunMetricsDiff,TokenUsageDiff,ToolCallsDiff,ToolCallsDiffSummaryDifcFilteredEvent,GatewayServerMetrics,GatewayToolMetrics,GuardPolicyEvent,MCPServerHealthDetail,MCPToolDiffEntry,MCPToolsDiff,MCPToolUsageSummaryDevcontainerBuild,DevcontainerCodespaces,DevcontainerCustomizations,DevcontainerRepoPermissions,DevcontainerVSCodeAmbientContextMetrics,AwInfoSteps,CopilotWorkflowStep,CreatedItemReport,PollResult,PolicyRule,SafeOutputChainMetrics,WorkflowRun, …pkg/console/README.mdNewProgressBar,NewIndeterminateProgressBar, and(*ProgressBar).Update(previously only referenced in prose examples)